home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / ifl / iflMT.z / iflMT
Encoding:
Text File  |  2002-10-03  |  24.3 KB  |  529 lines
  1.  
  2.  
  3.  
  4. iiiiffffllllMMMMTTTT((((3333))))          IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll           iiiiffffllllMMMMTTTT((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      iiiiffffllllMMMMTTTT,,,, iiiiffffllllQQQQTTTT,,,, iiiiffffllllMMMMVVVV - a multi-track movie file
  10.  
  11.  
  12. HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
  13.      #include <ifl/iflMT.h>
  14.  
  15.  
  16. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  17.      Movie files consist of image and audio data, which are stored in parallel
  18.      tracks.  A movie file may consist of multiple tracks of data, and each
  19.      track may contain either image or audio information.  A movie file's
  20.      multi-track structure is very useful in multi-media applications where
  21.      visual output in one track has to be synchronized with audio output in
  22.      another.
  23.  
  24.      This structure, which allows related data to be grouped together while
  25.      remaining in separate and distinct tracks, makes movie files a logical
  26.      storage format for confocal microscopes.  In many cases, users of
  27.      confocal microscopes examine a single sample at multiple wavelengths;  it
  28.      only makes sense to store data generated from these separate channels (or
  29.      "labels") in different image tracks.
  30.  
  31.  
  32.    AAAAbbbboooouuuutttt MMMMuuuullllttttiiii----ttttrrrraaaacccckkkk ffffiiiilllleeee oooobbbbjjjjeeeeccccttttssss....
  33.      The Image Format Library does not support the concept of "tracks":  IFL
  34.      assumes that all datafiles consist of a single track of data laid out in
  35.      sequential fashion. For image files containing multi-track data, this
  36.      causes two problems:
  37.  
  38.  
  39.      1.  IFL does not provide any generic mechanism to switch between
  40.          different tracks in a single image file.  Fortunately, IFL provides a
  41.          way around this:  the iflFile base class (which defines the core
  42.          functionality of all IFL file objects) includes "getTag" and "setTag"
  43.          methods that can be used to fetch and modify various attributes of an
  44.          image file.  Both the QuickTime and SGI derived objects provide
  45.          extensions to these methods that allow applications to change the
  46.          current track that is operated upon.
  47.  
  48.  
  49.      2.  Since the IFL cache has no notion of multiple tracks of image data,
  50.          it will get hopelessly confused if an application changes the image
  51.          track currently being operated on.  For example, suppose an
  52.          application read frames 0, 1, and 2 from track #0 into the IFL
  53.          caches, then changes the current track to track #1.  Clearly, we need
  54.          to load frames 0, 1, and 2 again, since we are dealing with a
  55.          different track of image; as far as the IFL cache is concerned,
  56.          however, there is no need to reload images 0, 1, and 2 of track #1,
  57.          as they are already resident in memory;
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. iiiiffffllllMMMMTTTT((((3333))))          IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll           iiiiffffllllMMMMTTTT((((3333))))
  71.  
  72.  
  73.  
  74.          The user MUST flush the IFL cache whenever it is changed.  Since the
  75.          iflFile object (which is the base class of iflMTFile object) is not
  76.          derived from the ilCacheImg class, it cannot automatically flush the
  77.          cache for the user.  The user application flushes the cache by
  78.          calling the "flush" method of the ilFileImg object as follows:
  79.  
  80.                ilFileImg *fileImage;
  81.  
  82.                fileImage->flush(TRUE);
  83.  
  84.  
  85.  
  86.    FFFFuuuunnnn FFFFaaaaccccttttssss
  87.      1.  QuickTime and Movie files support only one compression mode each for
  88.          write operations (read operations seem to be able to recognize more.)
  89.          Quicktime supports iflPACKBITS, and SGI supports iflSGIRLE.  Both
  90.          modes support iflNoCompression.
  91.  
  92.  
  93.      2.  I have only tested this code for reading and writing image files with
  94.          sequential pixel ordering (i.e. iflSequential.)  I have no idea how
  95.          it will behave with iflSeparate pixel ordering (where the pixel
  96.          components are stored on separate planes.)  Since the vast majority
  97.          of movie files use sequential pixel ordering, this shouldn't be a
  98.          problem.
  99.  
  100.  
  101.      3.  Deleting a frame or a track from a movie file does NOT result in the
  102.          automatic release of the disk storage space used by that frame or
  103.          track; deleted frames and tracks remain in the movie file as a
  104.          place-holder. Users should use the iflMToptimizeMovie extension to
  105.          the setTag method to force the movie file to release the unused space
  106.          taken up by deleted frames or tracks.
  107.  
  108.  
  109.      4.  The "correct" way to insert a new image to a file in IFL is to call
  110.          the "appendImg" method.  AppendImg is used by the iflMTFile object to
  111.          create a space holder image, which is later written over by the
  112.          object's setPage method.  Since the place holder is always deleted,
  113.          the resulting file will always have to be optimized, which is a very
  114.          time-consuming process.  As described above, deleting an image does
  115.          not free up the its disk space.  This method of appending images is
  116.          not very efficient.
  117.  
  118.          As an alternative, an extension has been provided that allows the
  119.          application to create an image and write to it in one step.  This
  120.          extension is called iflMTinsertFrame, and is invoked using the
  121.          "setTag" method.  As long as no frames or tracks are deleted, movie
  122.          files created this way do not need to be optimized.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. iiiiffffllllMMMMTTTT((((3333))))          IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll           iiiiffffllllMMMMTTTT((((3333))))
  137.  
  138.  
  139.  
  140. MMMMuuuullllttttiiii----ttttrrrraaaacccckkkk ssssuuuuppppppppoooorrrrtttt
  141.    SSSSeeeettttttttiiiinnnngggg mmmmuuuullllttttiiii----ttttrrrraaaacccckkkk aaaattttttttrrrriiiibbbbuuuutttteeeessss uuuussssiiiinnnngggg sssseeeettttTTTTaaaagggg(((())))
  142.      The following operations extend the generic IFL setTag mechanism to
  143.      support multi-track movie files, allowing a user to select a single
  144.      track, set movie, track and image (in QuickTime files) parameters, append
  145.      a track, remove a track, and optimize the movie file.  The prototype of
  146.      the setTag method is:
  147.  
  148.                iflStatus iflQTFile::setTag(int tag, va_list ap);
  149.  
  150.                input : tag - token identifying the type of item to be set.
  151.                        ap  - variable list containing items to be set.
  152.  
  153.      The tag parameter identifies the operation to be performed, and the
  154.      variable list contains the parameters required by the specified
  155.      operation.  Since the contents of the variable list are NOT checked, the
  156.      application programmer must be VERY careful to pass the correct values,
  157.      the correct TYPE of values, and the correct NUMBER of values in the
  158.      correct order.  The following list describes the extensions available
  159.      using the ifl setTag mechanism.
  160.  
  161.         tag: iflMTsetFrameTaggedParam
  162.           description: inserts the string pointed to by "tag_data" into the
  163.                         the parameter list of the current frame.  The string
  164.                         is referenced by the name string pointed to by
  165.                         "tag_name".
  166.           parameter 1: char* tag_name
  167.           parameter 2: char* tag_data
  168.  
  169.         tag: iflMTsetFrameAllParams
  170.           description: inserts an array of strings pointed to by "tags" into
  171.                         the parameter list of the current frame.  These
  172.      strings
  173.                         are referenced by name strings contained in the string
  174.                         array pointed to by "labels".  Both the tags and
  175.      labels
  176.                         arrays contain the number of strings specified by the
  177.                         "number_of_strings" parameter; there is a one-to-one
  178.                         correspondence between the data strings in the "tags"
  179.                         array and the name strings in the "labels" array.
  180.           parameter 1: int number_of_strings
  181.           parameter 2: char** labels
  182.           parameter 3: char** tags
  183.  
  184.         tag: iflMTsetMovieHeaderTaggedParam
  185.           description: inserts the string pointed to by "tag_data" into the
  186.                         the parameter list of the movie.  The string
  187.                         is referenced by the name string pointed to by
  188.                         "tag_name".
  189.            parameter 1: char* tag_name
  190.            parameter 2: char* tag_data
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. iiiiffffllllMMMMTTTT((((3333))))          IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll           iiiiffffllllMMMMTTTT((((3333))))
  203.  
  204.  
  205.  
  206.         tag: iflMTsetMovieHeaderAllParams
  207.           description: inserts an array of strings pointed to by "tags" into
  208.                         the parameter list of the movie.  These strings
  209.                         are referenced by name strings contained in the string
  210.                         array pointed to by "labels".  Both the tags and
  211.      labels
  212.                         arrays contain the number of strings specified by the
  213.                         "number_of_strings" parameter; there is a one-to-one
  214.                         correspondence between the data strings in the "tags"
  215.                         array and the name strings in the "labels" array.
  216.            parameter 1: int number_of_strings
  217.            parameter 2: char** labels
  218.            parameter 3: char** tags
  219.  
  220.         tag: iflMTsetTrackHeaderTaggedParam
  221.           description: inserts the string pointed to by "tag_data" into the
  222.                         the parameter list of the track.  The string
  223.                         is referenced by the name string pointed to by
  224.                         "tag_name".
  225.            parameter 1: char* tag_name
  226.            parameter 2: char* tag_data
  227.  
  228.         tag: iflMTsetTrackHeaderAllParams
  229.           description: inserts an array of strings pointed to by "tags" into
  230.                         the parameter list of the track.  These strings
  231.                         are referenced by name strings contained in the string
  232.                         array pointed to by "labels".  Both the tags and
  233.      labels
  234.                         arrays contain the number of strings specified by the
  235.                         "number_of_strings" parameter; there is a one-to-one
  236.                         correspondence between the data strings in the "tags"
  237.                         array and the name strings in the "labels" array.
  238.            parameter 1: int    number_of_strings
  239.            parameter 2: char** labels
  240.            parameter 3: char** tags
  241.  
  242.         tag: iflMTappendImageTrack
  243.           description: appends a new image track to the movie at the current
  244.                         track index; all following tracks are bumped one
  245.                         position.
  246.            parameter 1: int xSize
  247.            parameter 2: int ySize
  248.            parameter 3: iflColorModel  colorModel
  249.            parameter 4: iflOrientation orientation
  250.            parameter 5: iflCompression compression
  251.  
  252.         tag: iflMTappendAudioTrack
  253.           description: appends a new audio frame to the current track at the
  254.                         current index; all following frames are bumped one
  255.                         posiion.  This extension assumes that the current
  256.                         track is an audio track.
  257.            parameter 1: int    bitsPerSample
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. iiiiffffllllMMMMTTTT((((3333))))          IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll           iiiiffffllllMMMMTTTT((((3333))))
  269.  
  270.  
  271.  
  272.            parameter 2: double samplingRate
  273.  
  274.         tag: iflMTremoveCurrentTrack
  275.           description: removes the current track from the movie.
  276.           No parameters.
  277.  
  278.         tag: iflMTsetCurrentTrack
  279.           description: selects the current track of the movie file.  This
  280.      track
  281.                        may be either an audio or an image track.
  282.           parameter 1: int index
  283.  
  284.         tag: iflMTsetImageTrack
  285.           description: selects an image track to be the current track.
  286.           parameter 1: int index
  287.  
  288.         tag: iflMTsetAudioTrack
  289.           description: selects an audio track to be the current track.
  290.           parameter 1: int index
  291.  
  292.         tag: iflMTinsertFrame
  293.           description: inserts an image frame into the current track at the
  294.                         current frame index.  This extension assumes that the
  295.                         current track is an image track.
  296.           parameter 1: void* ptr
  297.           parameter 2: int   length
  298.  
  299.          tag: iflMTremoveFrame
  300.           description: deletes the current frame from the current track.
  301.           No parameters.
  302.  
  303.         tag: iflMToptimizeMovie
  304.           description: cleans up the movie file, removing all deleted images
  305.                         from the movie file.
  306.  
  307.  
  308.    FFFFeeeettttcccchhhhiiiinnnngggg mmmmuuuullllttttiiii----ttttrrrraaaacccckkkk aaaattttttttrrrriiiibbbbuuuutttteeeessss uuuussssiiiinnnngggg ggggeeeettttTTTTaaaagggg(((())))
  309.      The following operations extend the generic IFL "getTag" mechanism to
  310.      support multi-track movie files, allowing a user to determine the state
  311.      of the multi-track file.  Using "getTag", an application can query the
  312.      current track; read movie, track and image (for QuickTime files)
  313.      parameters; determine the frame height and width; and query the track
  314.      medium.
  315.  
  316.      The prototype of the getTag method is:
  317.  
  318.               iflStatus iflQTFile::getTag(int tag, va_list ap)
  319.  
  320.               input : tag - token identifying the type of item to be read.
  321.                       ap  - variable list containing items to be read.
  322.  
  323.      The tag parameter identifies the operation to be performed, and the
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. iiiiffffllllMMMMTTTT((((3333))))          IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll           iiiiffffllllMMMMTTTT((((3333))))
  335.  
  336.  
  337.  
  338.      variable list contains the parameters required by the specified
  339.      operation.  Since the contents of the variable list are NOT checked, the
  340.      application programmer must be VERY careful to pass the correct values,
  341.      the correct TYPE of values, and the correct NUMBER of values in the
  342.      correct order.  The following list describes the extensions available
  343.      using the ifl getTag mechanism.
  344.  
  345.          tag: iflMTgetFrameTaggedParam
  346.            description: retrieves the data string referred to by the name
  347.      string
  348.                          pointed by "tag_name" from the parameter list of the
  349.                          current image frame.  This data string is placed
  350.                          into the string pointed to by "tag_data".  The
  351.      maximum
  352.                          length of the "tag_data string is contained in
  353.                         "dst_length".
  354.            parameter 1: char* tag_name
  355.            parameter 2: int   dst_length
  356.            parameter 3: char* tag_data
  357.  
  358.           tag: iflMTgetFrameAllParams
  359.             description: retrieves the data strings referred to by the name
  360.                           strings stored in "labels" from the parameter list
  361.      of
  362.                           the current image frame.  These data strings are
  363.                           stored in the string array "tags".  The maximum
  364.      length
  365.                           of all strings stored in "tags" is stored in
  366.                           "max_string_length", and the number of strings
  367.      stored
  368.                           in both "labels" and "tags" is contained in
  369.                           "number_of_strings".  There is a one-to-one
  370.                           correspondence between the name strings stored in
  371.                           "labels" and the data strings stored in "tags".
  372.             parameter 1: int number_of_strings
  373.             parameter 2: char** labels
  374.             parameter 3: char** tags
  375.             parameter 4: int    max_string_length
  376.  
  377.            tag: iflMTgetTrackHeaderTaggedParam
  378.             description: retrieves the data string referred to by the name
  379.      string
  380.                           pointed by "tag_name" from the parameter list of the
  381.                           current track.  This data string is placed
  382.                           into the string pointed to by "tag_data".  The
  383.      maximum
  384.                           length of the "tag_data string is contained in
  385.                           "dst_length".
  386.             parameter 1: char* tag_name
  387.             parameter 2: int   dst_length
  388.             parameter 3: char* tag_data
  389.  
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. iiiiffffllllMMMMTTTT((((3333))))          IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll           iiiiffffllllMMMMTTTT((((3333))))
  401.  
  402.  
  403.  
  404.            tag: iflMTgetTrackHeaderAllParams
  405.             description: retrieves the data strings referred to by the name
  406.                           strings stored in "labels" from the parameter list
  407.      of
  408.                           the current track.  These data strings are
  409.                           stored in the string array "tags".  The maximum
  410.      length
  411.                           of all strings stored in "tags" is stored in
  412.                           "max_string_length", and the number of strings
  413.      stored
  414.                           in both "labels" and "tags" is contained in
  415.                           "number_of_strings".  There is a one-to-one
  416.                           correspondence between the name strings stored in
  417.                           "labels" and the data strings stored in "tags".
  418.             parameter 1: int number_of_strings
  419.             parameter 2: char** labels
  420.             parameter 3: char** tags
  421.             parameter 4: int    max_string_length
  422.  
  423.            tag: iflMTgetMovieHeaderTaggedParam
  424.             description: retrieves the data string referred to by the name
  425.      string
  426.                           pointed by "tag_name" from the parameter list of the
  427.                           movie.  This data string is placed into the string
  428.                           pointed to by "tag_data".  The maximum length of the
  429.                           "tag_data string is contained in "dst_length".
  430.             parameter 1: char* tag_name
  431.             parameter 2: int   max_string_length
  432.             parameter 3: char* tag_data
  433.  
  434.            tag: iflMTgetMovieHeaderAllParams
  435.             description: retrieves the data strings referred to by the name
  436.                           strings stored in "labels" from the parameter list
  437.      of
  438.                           the movie.  These data strings are stored in the
  439.                           string array "tags".  The maximum length of all
  440.                           strings stored in "tags" is stored in
  441.                           "max_string_length", and the number of strings
  442.      stored
  443.                           in both "labels" and "tags" is contained in
  444.                           "number_of_strings".  There is a one-to-one
  445.                           correspondence between the name strings stored in
  446.                           "labels" and the data strings stored in "tags".
  447.             parameter 1: int number_of_strings
  448.             parameter 2: char** labels
  449.             parameter 3: char** tags
  450.             parameter 4: int    max_string_length
  451.  
  452.            tag: iflMTgetNumberOfTracks
  453.             description: retrieves the number of tracks in the movie and
  454.      places
  455.                           it in the location pointed to by "number_of_tracks."
  456.  
  457.  
  458.  
  459.                                                                         PPPPaaaaggggeeee 7777
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. iiiiffffllllMMMMTTTT((((3333))))          IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll           iiiiffffllllMMMMTTTT((((3333))))
  467.  
  468.  
  469.  
  470.             parameter 1: int*  number_of_tracks
  471.  
  472.            tag: iflMTgetNumberOfFramesInTrack
  473.             description: retrieves the number of frames in the current track
  474.      and
  475.                           places it in the location pointed to by
  476.                           "number_of_frames".
  477.             parameter 1: int* number_of_frames
  478.  
  479.            tag: iflMTgetFrameHeight
  480.             description: retrieves the number of pixels in the vertical
  481.      dimension
  482.                           in the current frame and places it in the location
  483.                           pointed to by "height".
  484.             parameter 1: int* height
  485.  
  486.            tag: iflMTgetFrameWidth
  487.             description: retrieves the number of pixels in the horizontal
  488.                           dimension in the current frame and places it in the
  489.                           location pointed to by "height".
  490.             parameter 1: int* width
  491.  
  492.            tag: iflMTgetNumberOfAudioTracks
  493.             description: retrieves the number of audio tracks in the movie and
  494.                           places it in the location pointed to by
  495.                           "number_of_audio_tracks".
  496.             parameter 1: int* number_of_audio_tracks
  497.  
  498.            tag: iflMTgetNumberOfImageTracks
  499.             description: retrieves the number of image tracks in the movie and
  500.                           places it in the location pointed to by
  501.                           "number_of_image_tracks".
  502.             parameter 1: int* number_of_image_tracks
  503.  
  504.            tag: iflMTgetTrackMedium
  505.             description: determines the type of medium stored in the current
  506.                           track and places it in the location pointed to by
  507.                           "track_medium".
  508.             parameter 1: int* track_medium
  509.  
  510.         Returns: if iflOKAY => tagged data successfully read from Movie frame.
  511.                  else       => error reading tagged data from Movie frame.
  512.  
  513.  
  514. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  515.      iflFile, ilFileImg,
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.                                                                         PPPPaaaaggggeeee 8888
  526.  
  527.  
  528.  
  529.